Create OC Essential Service from Lead with Tenant Id

Create OC Essential Service from Lead with Tenant Id enables you to create a customer service with a SIP Connection created between the customer tenant service and the SBC device (OnlinePSTNGateway) (configured to connect calls between the PSTN trunk and Microsoft Teams) using the customer's Microsoft Azure tenant Id (see Create Customer from Lead with Tenant Id).

URI

Copy 
{{baseUrl}}/api/v3/customer

HTTP Method

POST

Request Body

Parameter

Type

Description

ConfigurationName

string
■ OcEssential_TENANT_TYPE

CustomerShortName

string

Customer short name with the following validation rules:

■ Length between 3 and 15 characters
■ No spaces
■ Include only literal and numerical characters and underscores

CustomerFulName

string

Generally the company name, however, any value can be used.

siteLocation
■ siteLocationName: string
■ sbcId: integer
■ sbcOnboardingScript: integer
■ sbcCleanupScript: integer
■ sbcOcUploadNumberScript: integer
■ sbcOcReleaseNumberScript: integer

The configured SBC used to manage calls for this site location.

siteLocationName

string

The name of the primary SIP connection for this service.

sbcId

integer

The SBC Id in the SBC List in the Live Platform database (see Get SBC Devices).

sbcOnboardingScript

integer

The SBC Onboarding script number in the Live Platform database (see Get Script Templates).

sbcCleanupScript

integer

The matching script number in the Live Platform database for Cleanup of the Onboarding script (see Get Script Templates).

sbcOcUploadNumberScript

integer

The script number in the Live Platform database for uploading numbers to the Operator Connect service (see Get Script Templates).

sbcOcReleaseNumberScript

integer

The matching script number in the Live Platform database to release numbers from the Operator Connect service (see Get Script Templates).

ovocCustomerType

■ IPGROUP_TYPE string
■ TENANT_TYPE string
■ IP Group: An IP Group is created for each new customer based on the Customer Shortname. This type is used for the Access Trunk Direct Routing (used for Direct Routing customers when SIP Registration is required).
■ Tenant ID:-The new customer is created based on the Tenant's Azure ID.

channelId

string

Id of the channel to attach to the service.

lcCustomerId

string

The Id of the Customer entity in the Operation Center portal. When you specify this value, the new service is created under this entity in the Live Platform topology tree.

This value is currently not retrievable using the REST API. If not specified, both a new customer and service entity are created as separate entities in the Operation Center portal with the same shortName as shown in the example figures below.

Workaround: As a temporary workaround for retrieving this value:

1. Select the relevant customer entity in the Operation Center portal.
2. Open the F12 Debugging mode, select the tabs as shown in the figure below.
3. Copy the 'id' value for the relevant customer.

If you cannot find the relevant value for your customer verify that the number of entries displayed includes your customer. If not, change the page filters to display more entries

msTenantId

string

Microsoft subscription Tenant ID of the Customer lead.

leadId

string

The Id generated for the lead (see Get All OC Leads)

invitationEmail

string

Email of the customer tenant Global Admin or Service account operator used for Onboarding and securing the connection to the customer M365 platform.

licenseType

integer

OC Essential: 3

licensedUsersCount

integer

The number of user licenses to allocate for the service.

umpCustomerGuid

string($uuid)

CustomerGuid created for the customer tenant when Live Cloud OC license is applied.

■ If this field has a value: The Guid of customer created by the Live Platform for the OC lead with the given msTenantid. This value is equivalent to the Id value extracted using Get Services Brief Details (V3).
■ If this field is null: An OC license has not yet been applied to the customer lead.

teamsQos
■ applicationID string
■ applicationPassword string

Credentials of the Application Registration on the customer tenant to connect to the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users. This registration must be added to the customer tenant (see Managing Teams Devices).

applicationID

string

The Application (Client) Id of the Application Registration for connecting to the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users.

applicationPassword

string

The Client Secret of the Microsoft Teams Notification Service for retrieving Microsoft Teams calls made by M365 tenant users.

scriptParameters refers to:

CustomVar.Variable<VariableSequenceNumber>

dictionary

where <VariableSequenceNumber> is the sequence in database that the variable is defined in the 'Customer variables' column for the script properties (see Customer Variables).

For example, when the following IP-PBX variables are defined in the database in the order: IPPBX-ProxyAddress, IPPBX-ProxyAddress-SIPPort, SIP-HostName then Custom variables should be defined as follows:

■ CustomVar.Variable1: <: IPPBX-ProxyAddress>
■ CustomVar.Variable2: < IPPBX-ProxyAddress-SIPPort>
■ CustomVar.Variable3: <SIP-HostName>

 

Custom variables can be defined to update specific parameters on the SBC device. These variables must be predefined in the UMP-365 database (see Customer Variables). Also verify that the custom variables notation has been added to the script (see parameter 'sbcOnboardingScript' above) that you are applying to the request.

There are three fields displayed in the schema additionalProp1-3, however there is no limitation for the number of variables that can be added.

additionalProp1

string

Custom Script variable argument. For example IP-Network.

additionalProp2

string

Custom Script argument. For example, IP-SubnetBits.

additionalProp3

string

Custom Script argument. For example, Trusted-IP-Network.

webhooks
■ invitationIsPending string
■ customerCreated string
■ didChange string

Webhooks push notification details (see Trigger Notification Email for New Leads).

The API requests for this feature are currently not supported.

invitationIsPending

string

Indicates that the Customer Invitation is pending for completion of the Invitation wizard process to secure connection with the customer M365 platform either through Delegated Token or Application Registration connection.

customerCreated

string

Indicates that the connection to the customer platform has been successfully secured and the service has been successfully created.

didChange

string

Indicates that a number has been uploaded or released for a service.

CallingProfileConfigurationTemplateId

integer

The Id of the Calling Profile Template.

This value can currently only be retrieved from the Web interface.

Example Request Body

Copy 
 {
  "statusChange": "OCEssential",
  "customerShortName": "Tenant_Walter2",
  "customerFullName": "Walter's Tenant2"

}

Example Response

The initial response displays the Task Id.

Parameter

Type

Description

taskId

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the wst string in the prefix is unique for this endpoint.
Copy 
"wst_501f59e0-997c-4545-be3b-a95b200926a2"

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'.

Copy 
{
    "id": "wst_501f59e0-997c-4545-be3b-a95b200926a2",
    "status": "CompletedSuccess",
    "details": [
        "Converted"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "Site created in Ovoc"
        }
    ],
    "outputData": {}
}

Response Codes

■ 200 Success

Parameter

Type

Description

id

string

Task Id

status

string

One of the following values:

■ In Progress
■ Completed Success
■ Completed Failed

details

string

One of the following values:

■ Converted

executionMessages

list array

List array including the following parameters:

■ level
■ message

level

string

One of the following values:

■ Information
■ Error

message

string

The following message is displayed in the output of the Get Task Id request, if the customer is created successfully:

Copy 
 "message": "Site created in Ovoc"
■ The following Request body includes a customer name with more than 15 characters.
Copy 
{
"statusChange": "OCEssential",
"customerShortName": "BradEurope1234567",
"customerFullName": "BradEurope1234567"
 
}
✔ As a result, the following error is received in the output for this request:
Copy 
{
    "errors": {
        "CustomerName": [
            "'Customer Short Name' must be between 3 and 15 characters."
        ]
    },
    "title": "One or more validation errors occurred.",
    "status": 400
}
■ The following Request body includes an invalid character ".":
Copy 
{
  "statusChange": "OCEssential",
  "customerShortName": "BradEurope.1234",
  "customerFullName": "BradEurope.1234"
  

}
✔ As a result, the following error is received in the output for this request:
Copy 
{
    "errors": {
        "CustomerName": [
            "Customer Short Name contains invalid characters. Allowed characters: letters, numbers and '_'."
        ],
        "CustomerFullName": [
            "Customer Full Name contains invalid characters. Allowed characters: letters, numbers, _, ' and space."
        ]
    },
    "title": "One or more validation errors occurred.",
    "status": 400
}

umpCustomerGuid

string($uuid)

CustomerGuid created for the customer tenant. This value is equivalent to the Id value extracted using Get Services Brief Details (V3).

If this field is null: An OC license has not yet been applied to the customer lead.

outputData

list array

Additional information.
■ 400 Bad Request

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

string

HTML error code i.e. 400

detail

string

Additional error details.

traceId

 

Error trace Id.

instance

string

Error instance.

Cac Profile

string

Information related to configured CAC sessions.

ProxySet

string

Information related to SBC Proxy Sets.

OnlinePstnGateway

string

Information related to OnlinePSTN Gateway of the SBC device attached to Calling Profiles (see Get Online PSTN Gateway.
■ 404 Not Found
■ The following example shows an example 404 error for lead that is not valid.
Copy 
"Invalild lead"
■ 405 Method Not Allowed
■ 500 Server Error